Print
Hooks allow developers to implement logic, typically initialization functionality to dynamically subscribe to events. They can also cause custom events to be raised by operations which do not raise events by default or to register event handlers programmatically. The system invokes hooks during initialization before any application requests are serviced.
The Sitecore.Pipelines.Loader.LoadHooks pipeline processor in the initialize core pipeline iterates over the /configuration/sitecore/hooks/hook entries in web.config. Then it creates an object of each specified type and invokes its Initialize method.
Please notice, that Sitecore CMS supports hooks, but custom pipeline processors in the initialize core pipeline provide functionality equivalent to hooks with greater flexibility. Processors can be reused by any number of pipelines; hooks are always invoked during initialization. Familiarity with events, pipelines and pipeline processors is important before consideration of hooks.
Classes which implement hooks inherit from Sitecore.Events.Hooks.Hook class.
Implementing Hooks
Follow these steps to implement a hook:
- Create a class which implements the Initialize method of the Sitecore.Events.Hooks.IHook interface.
- Register this class as a /configuration/sitecore/hooks/hook entry in web.config:
<hook type = "<Namespace.IHookClass>, <Assembly>" />
Hooks support parameters to the class’s constructor in exactly the same manner as other objects managed by the system’s factory such as event handlers and pipeline processors. For example, you could declare the following hook example in web.config:
<hook type="Sitecore.AddParamatersToHook, Assembly">
<param desc="Param 1"> 10 </param>
<param desc="Param 2"> 00:00:05 </param>
<CustomParam1> 20 </CustomParam1>
<CustomParam2> true </CustomParam2>
</hook>
And handle the parameters by using the following code:
public class AddParamatersToHook : IHook
{
// Fields
private int m_param1 ;
private TimeSpan m_param2;
private int m_customparam1;
private bool m_customparam2;
// Methods
public AddParamatersToHook (string param1, string param2)
{
this.m_param1 = int.Parse(param1);
this.m_param2 = TimeSpan.Parse(param2);
}
public void Initialize()
{
//…
}
// Properties
public int CustomParam1
{
get
{
return this. m_customparam1;
}
set
{
this. m_customparam1 = value;
}
}
public bool CustomParam2
{
get
{
return this. m_customparam2;
}
set
{
this. m_customparam2 = value;
}
}
}
For an example of parameters handled by a hook please take a look at the Sitecore.Diagnostics.MemoryMonitorHook hook in web.config.
Examples of implementing hooks
This section contains examples of the hooks implementation.
Example 1. Getting the target item
One use of hooks would be to cause custom events to be raised for certain database operations which don’t raise events by default. Consider the following example.
The item being moved is passed as the first parameter and the GUID of its parent is passed as the second parameter to the item:moving event handlers. It is possible to attach code to the move action in the database engine which raises a custom event and passes the new parent item as a parameter to that custom event.
To raise a custom event which passes the item being moved and the new parent item to handlers for that event, compile the ItemEventHandler.cs code associated with this article into the Visual Studio project, then register a custom event in the /configuration/sitecore/events section of web.config (optionally register the handler in the default item:moving event as well in order to see the differences):
<event name="item:moving">
<handler type="Demo.Tasks.ItemEventHandler, Demo" method="OnItemMoving" />
</event>
<event name="custom:item:moving">
<handler type="Demo.Tasks.ItemEventHandler, Demo" method="OnItemMoving" />
</event>
Then register the hook in the /configuration/sitecore/hooks section of web.config:
<hook type="Demo.Tasks.CustomMovingEventHook, Demo" />
Download the ItemEventHandler.cs (ZIP archive, 2Kb).
Example 2. Creating a new custom event
This example how to add information about the publishing process into log files. Using the PublishEngineHook you can subscribe to the ItemProcessed event of the PublishEngine. When the publishing occurs, the OnPublishItemProcessed method outputs items which have been published.
- Compile PublishEngineHook.cs into the Visual Studio project.
- Register a custom event in the /configuration/sitecore/events section of web.config:
<event name=" publish:itemprocessed">
<handler type="Namespase.Class, Assembly" method="Method" />
</event>
- Register the hook in the /configuration/sitecore/hooks section of web.config:
<hook type="Hooks.PublishEngineHook, Hooks"/>
Download the PublishEngineHook.cs (ZIP archive, 1Kb).
Example 3. Translating URL addresses
The hook in this example allows to translate URL addresses. For instance, you can type http://site.net/ordnung in the browser bar and the hook will instruct Sitecore CMS to interpret this as the http://site.net/order URL. The MultiLanguageResolvePathCommand method in this example gets the ID of an item using the URL in a foreign language.
This example only illustrates the hook implementation and lacks the Translate method code which you should write yourself.
- Compile MultiLanguageResolvePathCommandHook.cs into the Visual Studio project.
- Register the hook in the /configuration/sitecore/hooks section of web.config:
<hook type="Hooks.MultiLanguageResolvePathCommandHook, Hooks"/>
Download the MultiLanguageResolvePathCommandHook.cs (ZIP archive, 1Kb).